.\" planter - Slackermedia Project Tree
.TH "planter" "8" ""  "Klaatu" ""
.SH "NAME"
planter \- Create a default, standard directory tree for a multimedia project 
.SH "SYNOPSIS"
\fBplanter\fP [project name] [options]
.SH "DESCRIPTION"
.PP 
Keeping assets organised for artistic endeavours is always difficult,
so establishing a directory tree that provides structure and order to
a multimedia project is important to the creation process, and vital
to the integrity of the archived project. However, creating a complex
directory tree each time a new project is created can be confusing and
tedious.
.PP
\fBPlanter\fP creates a standardised, full directory tree for
multimedia content creators.
.PP
.SH USING PLANTER
.PP
\fBPlanter\fP can be used as a text-based command in a shell, or with a GUI.
.PP
\fBPlanter\fP requires three pieces of infomation:
.IP
A project name, which serves as the top level directory.
.IP
A location where the new project tree will be placed (such as your
home directory, or your music folder, or an external drive).
.IP
The location of shared assets. If you are working in a group, then
this might be a location on a mapped network drive. If you are working
alone or only locally, then it might be /usr/local/share.
.PP
All of these options can be set from the shell or from the GUI, or a
combination of both.
.SH OPTIONS
.TP
.B ProjectName
.IP
The project name, which serves as the top level directory of your
project tree. It is best practise to prefer camelCase over spaces, and
to avoid special, non-alphanumeric characters.
.IP
The project name requires no flag in the shell. If no project name is
provided, then the default, as set in your Planter conf file, is used.
.TP
.B -d, --destination
Where you want your project tree to be placed. Default is the current directory.
.TP
.B -s, --shared
The location of shared media assets.
.TP
.B -t, --type
Project type to create. The default is the `default` project in tree.list. 
.IP
The convention in most large production houses is to place common
read-only assets, such as sample banks, soundfonts, extra fonts,
models, textures, clip art, and so on, in a shared location, such as
/usr/local/shared/artkit, so that all artists working on a project can
access common assets. Set the default shared location in the
Planter configuration file.
.IP
If you set a shared location, you can have Planter create symlinks to
that location.
.IP
If a shared location is set both in the configuration file and as an
option in the command, the one defined in your command is used.
.TP
.B -g, --gui
Launches \fBPlanter\fP in GUI mode, in case you do not want to use the
shell. This is the default in the Planter launcher (the
Planter .desktop file).
.TP
.B -q, --quiet
Turns off the notification system that alerts you that the directory
tree has been created.
.TP
.B -c, --config
Use an alternate tree.list (config, or template) file.
.TP
.B 
.SH CUSTOMIZING THE TEMPLATE
.PP
\fBPlanter\fP creates a project tree based on the contents of the template file.
.PP
Unless you point it to something else, Planter uses
~/.config/planter/tree.list, if it exists. Failing that, it defaults
to /etc/planter/tree.list.
.PP
The default file /etc/planter/tree.list contains sample project definitions, but you
are free to change the template to fit your needs. The configuration
file is in very simple YAML. This is an example:
.PP
blah:
  - mkdir: foo
  - symdir: %COMMON%/art/bar:bar
  - symfile: %COMMON%/art/bar/baz:baz
  - copyfile: /usr/share/doc/gcc/COPYING:LICENSE
.PP
In this example, the blah tree generates a directory foo, symlinks a
directory bar, symlinks the file baz, and copies the GPL license from
the GCC directory into your project directory. To use it, the command
is:
.PP
planter --type blah
.PP
A mkdir lines tell \fBPlanter\fP to make a new directory or
directories. For instance:
.IP
mkdir:video
mkdir:video/thumbnails
mkdir:video/video
.PP
creates a 'video' directory, inside of which are two directories
called 'thumbnails' and 'video'. 
.PP
This is a template, so all paths are relative to the project name that
the user gives to \fBPlanter\fP at runtime. In other words,
\fBPlanter\fP creates the folder structure defined in tree.list inside
of a top level directory called newSlackermediaProject, or whatever
name you tell \fBPlanter\fP to use when you run \fBPlanter\fP. A
project name should never appear in tree.list itself.
.PP
A symdir or symfile line creates a symlink (an "alias" or "shortcut")
to an existing directory or file, respectively, containing shared
assets. There are two kinds of symlink lines:
.IP
symlink:graphics:video/graphics
.PP
creates a symlink in the video folder called "graphics", which points
the graphics folder in the same project. This makes sure that the same
data is not being duplicated, and that the video editor is using the
same matte painting, title cards, and other graphical elements that
the graphic designer has been developing.
.PP
This line:
.IP
symlink:%COMMON/samples:sound/samples
.PP
similarly creates a symlink from the sound directory called "samples",
pointing to a shared location (represented by the variable
%COMMON%). In other words, %COMMON% gets replaced by \fBPlanter\fP to
whatever the user tells it is the shared location.
.PP
A copyfile line copies a file from one location into your project
folder with the name you provide.
.PP
You can have as many project types, using whatever name (except "var",
which is reserved) you want.
.TP
.SH SETTING DEFAULTS
.PP
Planter has two global variables that can be set in the configuration
file. These can both be overridden by executing the \fBplanter\fP with
the --shared and --destination options.
.PP
The var: entry in the configuration sets Planter defaults:
.TP
.B COMMON
The location of common or shared assets. The default is
/usr/local/share/ but in your production environment, it will probably
be different.
.TP
.B NAME
The default name of a new directory tree if no name is provided in the
command. If a file of the same name already exists, an integer is
appended to this name.
.TP
.B
.SH "SEE ALSO"
.nf
.I mkdir (1)
.URL http://slackermedia.info/planter
.URL http://gitlab.com:planter/planter.git
.fi
.PP
.SH "AUTHORS"
.nf
Klaatu (klaatu@member.fsf.org)
.fi
.PP
.SH "BUGS"
Report via email or on gitlab.com, or fix them and request a merge.
.fi
